📞 API de UsuarioContatos - Documentação Completa

📋 Visão Geral

A API de UsuarioContatos é responsável por toda a gestão de contatos dos usuários no sistema CordenaAi, incluindo cadastro, atualização, consulta e exclusão de informações de contato como telefones, celulares, emails, WhatsApp e outros meios de comunicação. Esta API fornece a base para comunicação e contato dos usuários, permitindo a organização de dados de contato e facilitando a comunicação entre responsáveis, atletas e instituições.

🎯 Endpoints Disponíveis

📞 UsuarioContatos - Gestão de Contatos de Usuários

1. GET /api/UsuarioContatos/usuario/{usuarioId}

Listar Contatos por Usuário

2. GET /api/UsuarioContatos/{id}

Obter Contato por ID

3. POST /api/UsuarioContatos

Criar Novo Contato

4. PUT /api/UsuarioContatos/{id}

Atualizar Contato

5. DELETE /api/UsuarioContatos/{id}

Excluir Contato

🔧 Modelo de Dados

Estrutura do UsuarioContato

UsuarioContatoCreateDto (Criação)

{
  "usuarioId": "string",
  "responsavelContatoId": "string",
  "tipo": 1,
  "valor": "string",
  "observacao": "string"
}

UsuarioContatoUpdateDto (Atualização)

{
  "usuarioId": "string",
  "responsavelContatoId": "string",
  "tipo": 1,
  "valor": "string",
  "observacao": "string"
}

UsuarioContatoReadDto (Leitura)

{
  "id": 1,
  "usuarioId": "string",
  "usuarioNome": "string",
  "responsavelContatoId": "string",
  "responsavelContatoNome": "string",
  "tipo": 1,
  "valor": "string",
  "observacao": "string",
  "dataCadastro": "datetime",
  "dataAtualizacao": "datetime"
}

Tipos de Contato (TipoContato)

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Cadastro de Contatos

POST /api/UsuarioContatos
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-123",
  "tipo": 2,
  "valor": "11987654321",
  "observacao": "Celular principal"
}

2. Busca de Contatos por Usuário

GET /api/UsuarioContatos/usuario/user-123
Authorization: Bearer {token}

3. Atualização de Contato

PUT /api/UsuarioContatos/contato-456
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-123",
  "tipo": 4,
  "valor": "11987654321",
  "observacao": "WhatsApp principal"
}

4. Visualização de Contato Específico

GET /api/UsuarioContatos/contato-456
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Regras de Negócio

Validações por Tipo de Contato

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo Completo de Cadastro

  1. Validação de dados no backend pela própria API
  2. POST /api/UsuarioContatos com dados validados
  3. Associação automática com usuário
  4. Envio de notificação para usuário (se configurado)
  5. Criação de registro no sistema

Fluxo de Atualização

  1. GET /api/UsuarioContatos/{id} para obter dados atuais
  2. Validação de alterações no backend pela própria API
  3. PUT /api/UsuarioContatos/{id} com dados atualizados
  4. Confirmação de atualização com dados atualizados

Fluxo de Exclusão

  1. Confirmação de exclusão no frontend
  2. DELETE /api/UsuarioContatos/{id} para remoção
  3. Confirmação de exclusão (204 No Content)
  4. Atualização da interface do usuário

🔧 Configurações Específicas

Tipos de Contato Suportados

Validações Específicas

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi